home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / dev / basic / RIBlitzLibs.lha / riblitzlibs / docs / RIZoneJoyLib.doc < prev   
Encoding:
Text File  |  1995-01-28  |  11.6 KB  |  350 lines
  1. -----------------------------------------------------------------------------
  2. ====                 RI ZoneJoy Library V1.5 (C)1994/95              ====
  3. -----------------------------------------------------------------------------
  4.  
  5.                  Joystick Routines Written By Steven Matty
  6.                  Zone Routines Written By Stephen McNamara
  7.                         ©1994 Leading Edge Software
  8.  
  9.  
  10. This library contains commands for setting up zones and testing the status
  11. of the joysticks attached to the Amiga.
  12.  
  13. New additions to this library allow you to have multiple lists of zones
  14. (refered to as zonetables in this doc).  To maintain compatibility with
  15. older versions of the library, zonetable 0 is equivalent of the original
  16. list of zones used in the library.  You cannot adjust the size of zonetable
  17. 0 (its size is 256 zones), nor can you delete it.  The new zonetables can
  18. be from 1 to 65536 in size, there are 16 available zonetable numbers.
  19.  
  20. All commands that change or test zones will work on the last zonetable that
  21. was selected with the command UseZoneTable.  The default table is number 0.
  22.  
  23. Command list:
  24.       ZoneInit [zone_num]|[start_zone,end_zone]
  25.       Setzone zone#,x1,y1,radius
  26.       Setzone zone#,x1,y1,x2,y2
  27.       a.w=Zone(x,y)
  28.       a.w=ZoneTest(start_zone[,end_zone],x,y)
  29.       ad.l=ZoneTable
  30.       size.l=ZoneTableSize (table#)
  31.       UseZoneTable table#
  32.       NewZoneTable table#,size
  33.       FreeZoneTable table#
  34.  
  35.       jf.b=JFire(joy#)
  36.       jv.b=JVert(joy#)
  37.       jh.b=JHoriz(joy#)
  38.       af.b=AllFire [bit_pattern]
  39.  
  40. Additions for this version (1.5):
  41.  
  42.     JAdaptorStatus On/Off
  43.     x1=GetZoneX1(zone#)
  44.     y1=GetZoneY1(zone#)
  45.     x2=GetZoneX2(zone#)
  46.     y2=GetZoneY2(zone#)
  47.  
  48.  
  49. Statement: ZoneInit
  50. ------------------------------------------------------------------------
  51. Modes  : Amiga/Blitz
  52. Syntax : ZoneInit [zone_num]|[start_zone,end_zone]
  53.  
  54.   This command is used to clear any zones currently set.  The optional
  55.   parameters allow you to select either a single zone or a range of zones
  56.   to reset.
  57.  
  58.  
  59. Statement/Function: Setzone
  60. ------------------------------------------------------------------------
  61. Modes  : Amiga/Blitz
  62. Syntax : Setzone zone#,x1,y1,radius
  63.          Setzone zone#,x1,y1,x2,y2
  64.  
  65.   This command lets you set up zones for testing.  The first version is
  66.   used when you want to set up a circular zone and the second when you want
  67.   a rectangular one.  With rectangular zones, x1,y1 should be the top left
  68.   corner of the rectangle and x2,y2 should be the bottom left.
  69.  
  70.   If used as a function, this command returns TRUE or FALSE to say whether
  71.   or not the change was made.
  72.  
  73.   Note: The max zone number for zonetable 0 is 255.
  74.   A zone number outside the range of the current table will
  75.         cause this command to abort.
  76.         Zones can be defined in any order.
  77.         Circular zones are used in exactly the same way as rectangular
  78.         ones.
  79.  
  80.  
  81. Function: Zone
  82. ------------------------------------------------------------------------
  83. Modes  : Amiga/Blitz
  84. Syntax : a.w=Zone(x,y)
  85.  
  86.   This command takes the co-ordinates x,y and checks to see if they are
  87.   inside any of the defined zones.  The zones are searched in order,
  88.   starting at 0 and going through to the size of the zonetable-1.  This
  89.   command will return the first zone that the co-ordinates were found to
  90.   be inside, you should note that both types of zones are tested
  91.   (rectangular and circular).
  92.  
  93.   This command returns either -1 for not inside a zone or the zone number.
  94.  
  95.  
  96. Function: ZoneTest
  97. ------------------------------------------------------------------------
  98. Modes  : Amiga/Blitz
  99. Syntax : a.w=ZoneTest(start_num[,end_num],x,y)
  100.  
  101.   This command is the same as the Zone command except that it allows you
  102.   to select either one individual zone to test or a range of zones.  You
  103.   should, though, ensure that end_num if greater than start_num.
  104.  
  105.   This command returns either -1 for not inside a zone or the zone number.
  106.  
  107.  
  108. Function: ZoneTable
  109. ------------------------------------------------------------------------
  110. Modes  : Amiga/Blitz
  111. Syntax : ad.l=ZoneTable
  112.  
  113.   This function returns the address in memory of the zone information
  114.   storage area for the current zonetable. The zones are stored one after
  115.   the other, with each zone taking up 8 words (16 bytes) in the data area,
  116.   making a total size of 2048 bytes.  They are stored in the following way:
  117.  
  118.     Rectangular:    +0: x1
  119.         +2: y1
  120.         +4: x2
  121.         +6: y2
  122.  
  123.     Circular: +0: x1
  124.         +2: y1
  125.         +4: radius of zone
  126.         +6: -1 <-- this is set to show that the
  127.                    zone is circular.
  128.  
  129.     Undefined zone: +0: -1
  130.         +2: -1
  131.         +4: -1
  132.         +6: -1
  133.  
  134.   The first longword (4 bytes) of the zonetable is used to hold the size,
  135. in zones, of the table (thus the true size of the zonetable is 4+number of
  136. zones*8).
  137.  
  138.  
  139. Function: ZoneTableSize
  140. ------------------------------------------------------------------------
  141. Modes  : Amiga/Blitz
  142. Syntax : size.l=ZoneTableSize
  143.  
  144.   This function returns the size, in zones, of the current zonetable.  It
  145. is equivalent of doing: size.l=peek.l(ZoneTable).
  146.  
  147.  
  148. Statement/Function: NewZoneTable
  149. ------------------------------------------------------------------------
  150. Modes  : Amiga/Blitz
  151. Syntax : NewZoneTable table#,size
  152.  
  153.   This command will attempt to allocate a new zonetable with the given
  154. table number.  If the table already exists it will be deleted.  The maximum
  155. size for a zonetable is 65536 zones.  If used as a function, this command
  156. will return FALSE for failure or TRUE for success.  You should note that
  157. all zones are automatically reset in the new table and that creating a
  158. table does not make it the current table, this must be done with
  159. UseZoneTable.
  160.   Valid zonetable numbers range from 0 to 15.
  161.  
  162.   IMPORTANT NOTE: you cannot define the size of zonetable 0.  You cannot
  163. use this command to alter it in any way.
  164.  
  165.  
  166. Statement/Function: UseZoneTable
  167. ------------------------------------------------------------------------
  168. Modes  : Amiga/Blitz
  169. Syntax : UseZoneTable table#
  170.  
  171.   This command is used to change the current zonetable to the selected one.
  172. If used as a function, it will return TRUE for success or FALSE for
  173. failure.
  174.   Valid zonetable numbers range from 0 to 15.
  175.  
  176.  
  177. Statement/Function: FreeZoneTable
  178. ------------------------------------------------------------------------
  179. Modes  : Amiga/Blitz
  180. Syntax : FreeZoneTable table#
  181.  
  182.   This command is used to free a zonetable from memory.  If used as a
  183. function, it will return TRUE or FALSE.  When successfully called, this
  184. command will free the zonetable and change the currently used zonetable to
  185. table number 0.
  186.   Valid zonetable numbers range from 0 to 15.
  187.  
  188.   IMPORTANT NOTE: you cannot free zone table 0.
  189.  
  190.  
  191. Function: JFire
  192. ------------------------------------------------------------------------
  193. Modes  : Amiga/Blitz
  194. Syntax : jf.b=JFire(joy#)
  195.  
  196.   This command tests the fire button status of the joystick joy#, where
  197.   joy# is between 1 and 4.  You should note that, as with all the joystick
  198.   commmands, joy#=1 refers to the Amiga's joystick port, joy#=2 refers to
  199.   the mouse port, and joy#=3 or joy#=4 refer to the four player adapter
  200.   ports.
  201.  
  202.   This command returns 0 for fire button not pressed or -1 for pressed
  203.  
  204.  
  205. Function: JHoriz
  206. ------------------------------------------------------------------------
  207. Modes  : Amiga/Blitz
  208. Syntax : jh.b=JHoriz(joy#)
  209.  
  210.   This command is used to test the horizontal direction of the selected
  211.   joystick.  It returns:
  212.  
  213.     0: No horizontal direction
  214.            -1: Joystick left
  215.           1: Joystick right
  216.  
  217.  
  218. Function: JVert
  219. ------------------------------------------------------------------------
  220. Modes  : Amiga/Blitz
  221. Syntax : jv.b=JVert(joy#)
  222.  
  223.   This command is used to test the vertical direction of the selected
  224.   joystick.  It returns:
  225.  
  226.     0: No vertical direction
  227.            -1: Joystick up
  228.           1: Joystick down
  229.  
  230.  
  231. Function: AllFire
  232. ------------------------------------------------------------------------
  233. Modes  : Amiga/Blitz
  234. Syntax : af.b=AllFire [(bit_pattern)]
  235.  
  236.   This command is used to test the fire button status of all four
  237.   joysticks.  It returns a byte with the first four bits giving the
  238.   joystick status, false=fire button not pressed, true=fire button pressed.
  239.   The following bits belong to joysticks:
  240.  
  241.     bit 0: joystick 1 (joystick port)
  242.     bit 1: joystick 2 (mouse port)
  243.     bit 2: joystick 3 (four player adaptor)
  244.     bit 3: joystick 4 (four player adaptor)
  245.  
  246.   The optional bit pattern can be used to restrict the testing of the fire
  247.   buttons.  If a bit in the pattern is clear (false) then the joystick it
  248.   belongs to will not have its fire button tested,
  249.  
  250.     e.g. AllFire (%0011) will test joysticks 1 and 2 and return the
  251.              result.  It will return false for joysticks 3 and 4.
  252.  
  253.  
  254. Statement/Function: JAdaptorStatus
  255. ------------------------------------------------------------------------
  256. Modes  : Amiga/Blitz
  257. Syntax : JAdaptorStatus On/Off
  258.      oldstatus=JAdaptorStatus(On/Off)
  259.  
  260. This command toggles the reading of the four player adaptor for the
  261. following commands:
  262.  
  263.         AllFire
  264.         Jvert
  265.         JHoriz
  266.         JFire
  267.  
  268. When the status is off, these commands will return 0 when you attempt to
  269. read from joysticks 3 and 4.  When on the testing will be performed
  270. normally.  Default status for the adaptor is on.
  271.  
  272.  
  273. Function: GetZoneX1
  274. ------------------------------------------------------------------------
  275. Modes  : Amiga/Blitz
  276. Syntax : x1=GetZoneX1 (zone#)
  277.  
  278. This command returns the x start position for the specified zone in the
  279. currently used zone table.  If the zone number supplied goes outside the
  280. size of the zonetable, then this command returns -1.  It also returns -1 if
  281. the zone is undefined.
  282.  
  283.  
  284. Function: GetZoneY1
  285. ------------------------------------------------------------------------
  286. Modes  : Amiga/Blitz
  287. Syntax : y1=GetZoneY1 (zone#)
  288.  
  289. This command returns the y start position for the specified zone in the
  290. currently used zone table.  If the zone number supplied goes outside the
  291. size of the zonetable, then this command returns -1.  It also returns -1 if
  292. the zone is undefined.
  293.  
  294.  
  295. Function: GetZoneX2
  296. ------------------------------------------------------------------------
  297. Modes  : Amiga/Blitz
  298. Syntax : x2=GetZoneX2 (zone#)
  299.  
  300. This command returns the x end position for the specified zone in the
  301. currently used zone table.  If the zone number supplied goes outside the
  302. size of the zonetable, then this command returns -1.  It also returns -1 if
  303. the zone is undefined.
  304.  
  305. Note: For circular zones, this command will return the radius of the circle
  306. squared.
  307.  
  308.  
  309. Function: GetZoneY2
  310. ------------------------------------------------------------------------
  311. Modes  : Amiga/Blitz
  312. Syntax : y2=GetZoneY2 (zone#)
  313.  
  314. This command returns the y end position for the specified zone in the
  315. currently used zone table.  If the zone number supplied goes outside the
  316. size of the zonetable, then this command returns -1.  It also returns -1 if
  317. the zone is undefined.
  318.  
  319. Note: For circular zones this command will always return -1
  320.  
  321.  
  322. ------------------------------------------------------------------------
  323.  
  324. Version details:
  325.  
  326. 27/1/95
  327.   - V1.5
  328.   - Fixed comparison prob in both 'circular:, changed BPL into
  329.     BGE.
  330.   - Fixed _zonetest000 - was getting x1,y,x2,y2 in wrong order
  331.   - Fixed _zonetest020 circular zones - same prob as above
  332.   - Added:
  333.         GetZoneX1/X2/Y1/Y2 for zone interrogating...
  334. 25/1/95
  335.   - Added JAdaptorStatus for disabling/enabling player
  336.     3 & 4 joystick reading.  If disabled, commands will return
  337.     0 for these joysticks.
  338.   - Added fourplayer checking to AllFire.
  339. 23/11/94
  340.   - BIG bug in ZoneInit2 - was moving #0 into (a1) instead
  341.       of (a0)
  342. 3/9/94
  343.   - Added 020 specific zone testing
  344.   - Added commands ZoneMode and SetZoneMode (for 020 support)
  345.   - Speed increase on Jfire: replaced branches and moveqs with
  346.      SEQ
  347.   - Improved jvert and jhoriz to remove inefficiency
  348.  
  349. >>END  
  350.